2026/08/14 - Amazon Bedrock AgentCore - 5 updated api methods
Changes Add support for the Machine Payments Protocol (MPP) and x402 upto scheme payments protocol in Amazon Bedrock AgentCore Payments. Customers can now pay for MPP-gated resources and also pay services which requires upto scheme in x402
{'paymentInstrument': {'status': {'BLOCKED'}}}
Create a new payment instrument for a connector.
See also: AWS API Documentation
Request Syntax
client.create_payment_instrument(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentType='EMBEDDED_CRYPTO_WALLET',
paymentInstrumentDetails={
'embeddedCryptoWallet': {
'network': 'ETHEREUM'|'SOLANA',
'linkedAccounts': [
{
'email': {
'emailAddress': 'string'
},
'sms': {
'phoneNumber': 'string'
},
'developerJwt': {
'kid': 'string',
'sub': 'string'
},
'oAuth2': {
'google': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'apple': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'x': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'telegram': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'github': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
}
}
},
],
'walletAddress': 'string',
'redirectUrl': 'string'
}
},
clientToken='string'
)
string
The user ID associated with this payment instrument.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this payment instrument.
string
[REQUIRED]
The ID of the payment connector to use for this instrument.
string
[REQUIRED]
The type of payment instrument being created.
dict
[REQUIRED]
The details of the payment instrument.
embeddedCryptoWallet (dict) --
Embedded crypto wallet managed directly by end user.
network (string) -- [REQUIRED]
The blockchain network for this embedded crypto wallet. Supported networks: ETHEREUM, SOLANA.
linkedAccounts (list) -- [REQUIRED]
List of linked accounts linked to this wallet. Each represents a way the end user can authenticate to this wallet.
(dict) --
Represents different linked accounts that can be linked to an embedded wallet. Supports email, SMS, JWT, and OAuth2 approaches.
email (dict) --
Email-based linked account.
emailAddress (string) -- [REQUIRED]
The email address used for the linked account. Must be a valid email format.
sms (dict) --
SMS-based linked account using phone number.
phoneNumber (string) -- [REQUIRED]
The phone number in E.164 format (e.g., +1234567890).
developerJwt (dict) --
Developer JWT linked account with key ID and subject.
kid (string) -- [REQUIRED]
The key ID (kid) from the JWT header. Identifies which key was used to sign the JWT.
sub (string) -- [REQUIRED]
The subject (sub) claim from the JWT payload. Identifies the principal that is the subject of the JWT.
oAuth2 (dict) --
OAuth2 provider linked account (Google, Apple, X, Telegram, GitHub).
google (dict) --
Google OAuth2 authentication.
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
apple (dict) --
Apple OAuth2 authentication.
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
x (dict) --
X (formerly Twitter) OAuth2 authentication.
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
telegram (dict) --
Telegram OAuth2 authentication.
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
github (dict) --
GitHub OAuth2 authentication.
sub (string) -- [REQUIRED]
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
walletAddress (string) --
The wallet address on the specified blockchain network.
redirectUrl (string) --
URL for the end user to complete a provider-specific action such as wallet linking or onboarding.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.
This field is autopopulated if not provided.
dict
Response Syntax
{
'paymentInstrument': {
'paymentInstrumentId': 'string',
'paymentManagerArn': 'string',
'paymentConnectorId': 'string',
'userId': 'string',
'paymentInstrumentType': 'EMBEDDED_CRYPTO_WALLET',
'paymentInstrumentDetails': {
'embeddedCryptoWallet': {
'network': 'ETHEREUM'|'SOLANA',
'linkedAccounts': [
{
'email': {
'emailAddress': 'string'
},
'sms': {
'phoneNumber': 'string'
},
'developerJwt': {
'kid': 'string',
'sub': 'string'
},
'oAuth2': {
'google': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'apple': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'x': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'telegram': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'github': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
}
}
},
],
'walletAddress': 'string',
'redirectUrl': 'string'
}
},
'createdAt': datetime(2015, 1, 1),
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED'|'BLOCKED',
'updatedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Response structure for creating a payment instrument.
paymentInstrument (dict) --
The created payment instrument.
paymentInstrumentId (string) --
The unique identifier for this payment instrument.
paymentManagerArn (string) --
The ARN of the payment manager that owns this payment instrument.
paymentConnectorId (string) --
The ID of the payment connector associated with this instrument.
userId (string) --
The user ID associated with this payment instrument.
paymentInstrumentType (string) --
The type of payment instrument (e.g., EMBEDDED_CRYPTO_WALLET).
paymentInstrumentDetails (dict) --
The details specific to the payment instrument type.
embeddedCryptoWallet (dict) --
Embedded crypto wallet managed directly by end user.
network (string) --
The blockchain network for this embedded crypto wallet. Supported networks: ETHEREUM, SOLANA.
linkedAccounts (list) --
List of linked accounts linked to this wallet. Each represents a way the end user can authenticate to this wallet.
(dict) --
Represents different linked accounts that can be linked to an embedded wallet. Supports email, SMS, JWT, and OAuth2 approaches.
email (dict) --
Email-based linked account.
emailAddress (string) --
The email address used for the linked account. Must be a valid email format.
sms (dict) --
SMS-based linked account using phone number.
phoneNumber (string) --
The phone number in E.164 format (e.g., +1234567890).
developerJwt (dict) --
Developer JWT linked account with key ID and subject.
kid (string) --
The key ID (kid) from the JWT header. Identifies which key was used to sign the JWT.
sub (string) --
The subject (sub) claim from the JWT payload. Identifies the principal that is the subject of the JWT.
oAuth2 (dict) --
OAuth2 provider linked account (Google, Apple, X, Telegram, GitHub).
google (dict) --
Google OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
apple (dict) --
Apple OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
x (dict) --
X (formerly Twitter) OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
telegram (dict) --
Telegram OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
github (dict) --
GitHub OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
walletAddress (string) --
The wallet address on the specified blockchain network.
redirectUrl (string) --
URL for the end user to complete a provider-specific action such as wallet linking or onboarding.
createdAt (datetime) --
The timestamp when this payment instrument was created.
status (string) --
The current status of this payment instrument.
updatedAt (datetime) --
The timestamp when this payment instrument was last updated.
{'status': {'BLOCKED'}}
Deletes a payment instrument. This is a soft delete operation that preserves the record for audit and compliance purposes.
See also: AWS API Documentation
Request Syntax
client.delete_payment_instrument(
userId='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentId='string'
)
string
The user ID making the delete request. Must match the instrument's userId.
string
[REQUIRED]
The payment manager ARN. Must match the instrument's paymentManagerArn.
string
[REQUIRED]
The payment connector ID. Must match the instrument's paymentConnectorId.
string
[REQUIRED]
The payment instrument ID to delete.
dict
Response Syntax
{
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED'|'BLOCKED'
}
Response Structure
(dict) --
Response structure for deleting a payment instrument.
status (string) --
The status of the instrument after deletion. Always DELETED for successful soft delete.
{'paymentInstrument': {'status': {'BLOCKED'}}}
Get a payment instrument by ID.
See also: AWS API Documentation
Request Syntax
client.get_payment_instrument(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
paymentInstrumentId='string'
)
string
The user ID associated with this payment instrument.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns this payment instrument.
string
The ID of the payment connector.
string
[REQUIRED]
The ID of the payment instrument to retrieve.
dict
Response Syntax
{
'paymentInstrument': {
'paymentInstrumentId': 'string',
'paymentManagerArn': 'string',
'paymentConnectorId': 'string',
'userId': 'string',
'paymentInstrumentType': 'EMBEDDED_CRYPTO_WALLET',
'paymentInstrumentDetails': {
'embeddedCryptoWallet': {
'network': 'ETHEREUM'|'SOLANA',
'linkedAccounts': [
{
'email': {
'emailAddress': 'string'
},
'sms': {
'phoneNumber': 'string'
},
'developerJwt': {
'kid': 'string',
'sub': 'string'
},
'oAuth2': {
'google': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'apple': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'x': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'telegram': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
},
'github': {
'sub': 'string',
'emailAddress': 'string',
'name': 'string',
'username': 'string'
}
}
},
],
'walletAddress': 'string',
'redirectUrl': 'string'
}
},
'createdAt': datetime(2015, 1, 1),
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED'|'BLOCKED',
'updatedAt': datetime(2015, 1, 1)
}
}
Response Structure
(dict) --
Response structure for getting a payment instrument.
paymentInstrument (dict) --
The payment instrument details.
paymentInstrumentId (string) --
The unique identifier for this payment instrument.
paymentManagerArn (string) --
The ARN of the payment manager that owns this payment instrument.
paymentConnectorId (string) --
The ID of the payment connector associated with this instrument.
userId (string) --
The user ID associated with this payment instrument.
paymentInstrumentType (string) --
The type of payment instrument (e.g., EMBEDDED_CRYPTO_WALLET).
paymentInstrumentDetails (dict) --
The details specific to the payment instrument type.
embeddedCryptoWallet (dict) --
Embedded crypto wallet managed directly by end user.
network (string) --
The blockchain network for this embedded crypto wallet. Supported networks: ETHEREUM, SOLANA.
linkedAccounts (list) --
List of linked accounts linked to this wallet. Each represents a way the end user can authenticate to this wallet.
(dict) --
Represents different linked accounts that can be linked to an embedded wallet. Supports email, SMS, JWT, and OAuth2 approaches.
email (dict) --
Email-based linked account.
emailAddress (string) --
The email address used for the linked account. Must be a valid email format.
sms (dict) --
SMS-based linked account using phone number.
phoneNumber (string) --
The phone number in E.164 format (e.g., +1234567890).
developerJwt (dict) --
Developer JWT linked account with key ID and subject.
kid (string) --
The key ID (kid) from the JWT header. Identifies which key was used to sign the JWT.
sub (string) --
The subject (sub) claim from the JWT payload. Identifies the principal that is the subject of the JWT.
oAuth2 (dict) --
OAuth2 provider linked account (Google, Apple, X, Telegram, GitHub).
google (dict) --
Google OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
apple (dict) --
Apple OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
x (dict) --
X (formerly Twitter) OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
telegram (dict) --
Telegram OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
github (dict) --
GitHub OAuth2 authentication.
sub (string) --
The subject (sub) claim from the OAuth2 provider. Uniquely identifies the user at the provider.
emailAddress (string) --
The email address from the OAuth2 provider.
name (string) --
The user's name from the OAuth2 provider.
username (string) --
The username from the OAuth2 provider.
walletAddress (string) --
The wallet address on the specified blockchain network.
redirectUrl (string) --
URL for the end user to complete a provider-specific action such as wallet linking or onboarding.
createdAt (datetime) --
The timestamp when this payment instrument was created.
status (string) --
The current status of this payment instrument.
updatedAt (datetime) --
The timestamp when this payment instrument was last updated.
{'paymentInstruments': {'status': {'BLOCKED'}}}
List payment instruments for a manager.
See also: AWS API Documentation
Request Syntax
client.list_payment_instruments(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentConnectorId='string',
nextToken='string',
maxResults=123
)
string
The user ID associated with the payment instruments.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager that owns the payment instruments.
string
The ID of the payment connector to filter by.
string
Token for pagination to retrieve the next set of results.
integer
Maximum number of results to return in a single response.
dict
Response Syntax
{
'paymentInstruments': [
{
'paymentInstrumentId': 'string',
'paymentManagerArn': 'string',
'paymentConnectorId': 'string',
'userId': 'string',
'paymentInstrumentType': 'EMBEDDED_CRYPTO_WALLET',
'status': 'INITIATED'|'ACTIVE'|'FAILED'|'DELETED'|'BLOCKED',
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
},
],
'nextToken': 'string'
}
Response Structure
(dict) --
Response structure for listing payment instruments.
paymentInstruments (list) --
List of payment instrument summaries matching the request criteria.
(dict) --
Summary of a payment instrument for list operations.
paymentInstrumentId (string) --
The unique identifier for this payment instrument.
paymentManagerArn (string) --
The ARN of the payment manager that owns this payment instrument.
paymentConnectorId (string) --
The ID of the payment connector associated with this instrument.
userId (string) --
The user ID associated with this payment instrument.
paymentInstrumentType (string) --
The type of payment instrument (e.g., EMBEDDED_CRYPTO_WALLET).
status (string) --
The current status of this payment instrument.
createdAt (datetime) --
The timestamp when this payment instrument was created.
updatedAt (datetime) --
The timestamp when this payment instrument was last updated.
nextToken (string) --
Token for pagination to retrieve the next set of results.
{'paymentInput': {'cryptoX402': {'permit2AllowanceLimit': 'string'},
'mpp': {'buyerPaysGasFees': 'boolean',
'version': 'string',
'wwwAuthenticateHeaders': ['string']}},
'paymentType': {'MPP'}}
Response {'paymentOutput': {'mpp': {'paymentCredential': 'string',
'selectedPaymentId': 'string',
'version': 'string'}},
'paymentType': {'MPP'}}
Processes a payment using a payment instrument within a payment session.
See also: AWS API Documentation
Request Syntax
client.process_payment(
userId='string',
agentName='string',
paymentManagerArn='string',
paymentSessionId='string',
paymentInstrumentId='string',
paymentType='CRYPTO_X402'|'MPP',
paymentInput={
'cryptoX402': {
'version': 'string',
'payload': {...}|[...]|123|123.4|'string'|True|None,
'permit2AllowanceLimit': 'string'
},
'mpp': {
'version': 'string',
'wwwAuthenticateHeaders': [
'string',
],
'buyerPaysGasFees': True|False
}
},
clientToken='string'
)
string
The user ID associated with this payment.
string
The agent name associated with this request, used for observability.
string
[REQUIRED]
The ARN of the payment manager.
string
[REQUIRED]
The ID of the payment session.
string
[REQUIRED]
The ID of the payment instrument to use.
string
[REQUIRED]
The type of payment to process.
dict
[REQUIRED]
The payment input details specific to the payment type.
cryptoX402 (dict) --
Input for a crypto X402 payment.
version (string) -- [REQUIRED]
The version of the X402 protocol.
payload (:ref:`document<document>`) -- [REQUIRED]
The X402 payment payload.
permit2AllowanceLimit (string) --
The maximum on-chain Permit2 allowance to grant before signing the payment authorization, in the asset's smallest denomination. This field is valid only for the upto (metered) scheme; supplying it for the exact scheme returns a validation error.
When set, the service approves an ERC-20 allowance for this amount before processing the payment. The approval sets, rather than adds to, the wallet's allowance. Set this field only when the wallet needs approving, for example on its first upto payment, to avoid a redundant on-chain transaction. Omit the field to skip allowance handling. This is the default, and the only behavior for the exact scheme.
mpp (dict) --
Contains the payment challenge from a 402 Payment Required response. Forward the raw WWW-Authenticate: Payment header value verbatim. In response, you receive a payment credential that satisfies the challenge. Provide exactly one challenge per request.
version (string) -- [REQUIRED]
The MPP protocol version, for example "1" or "2".
wwwAuthenticateHeaders (list) -- [REQUIRED]
The raw WWW-Authenticate: Payment header value from the 402 response, passed verbatim. Provide exactly one entry. The service uses this value to generate the payment credential.
(string) --
A raw WWW-Authenticate: Payment header value from a 402 response, containing RFC 9110 auth-params such as id, realm, method, intent, and request. Pass this value in the request body, not as an HTTP header.
buyerPaysGasFees (boolean) --
Authorizes the service to sign a payment whose blockchain network (gas) fees are charged to your wallet, on top of the payment amount.
The challenge indicates who sponsors the network fees. When the challenge does not sponsor them, the service signs the payment only if this field is true. Otherwise it returns a validation error, so you can decide whether to pay the fees or obtain a challenge that sponsors them.
Optional. When omitted or false, you decline to pay network fees. This field has no effect on challenges that already sponsor the fees.
string
A unique, case-sensitive identifier that you provide to ensure the idempotency of the request.
This field is autopopulated if not provided.
dict
Response Syntax
{
'processPaymentId': 'string',
'paymentManagerArn': 'string',
'paymentSessionId': 'string',
'paymentInstrumentId': 'string',
'paymentType': 'CRYPTO_X402'|'MPP',
'status': 'PROOF_GENERATED',
'paymentOutput': {
'cryptoX402': {
'version': 'string',
'payload': {...}|[...]|123|123.4|'string'|True|None
},
'mpp': {
'version': 'string',
'selectedPaymentId': 'string',
'paymentCredential': 'string'
}
},
'createdAt': datetime(2015, 1, 1),
'updatedAt': datetime(2015, 1, 1)
}
Response Structure
(dict) --
Response structure for processing a payment.
processPaymentId (string) --
The unique identifier of the processed payment.
paymentManagerArn (string) --
The ARN of the payment manager.
paymentSessionId (string) --
The ID of the payment session used.
paymentInstrumentId (string) --
The ID of the payment instrument used.
paymentType (string) --
The type of payment processed.
status (string) --
The status of the payment.
paymentOutput (dict) --
The payment output details specific to the payment type.
cryptoX402 (dict) --
Output from a crypto X402 payment.
version (string) --
The version of the X402 protocol.
payload (:ref:`document<document>`) --
The X402 payment response payload.
mpp (dict) --
Contains the payment credential, ready to retry the request.
version (string) --
The MPP protocol version, for example "1" or "2".
selectedPaymentId (string) --
The id of the challenge that was paid, echoed from the input challenge so you can correlate the result without decoding the credential.
paymentCredential (string) --
Ready-to-send value for the Authorization header, in the form "Payment <base64url-token>". Attach this header and retry the original request. To inspect the full credential, base64url-decode the token.
createdAt (datetime) --
The timestamp when the payment was created.
updatedAt (datetime) --
The timestamp when the payment was last updated.