Add Aptos payment mechanism by jtang17 · Pull Request #966 · coinbase/x402

jtang17 · 2026-01-15T02:24:58Z

Description

Add @x402/aptos package with exact scheme support
Implement SchemeNetworkClient, SchemeNetworkFacilitator, SchemeNetworkServer
Support sponsored transactions via extra.sponsored: true
Use 0x1::primary_fungible_store::transfer for fungible asset transfers
Add BCS serialization utilities for transaction encoding
Include facilitator signer with fee payer support
Add unit tests (23 passing) for types, constants, and exports
Update spec to use sponsored: true instead of gasStation URL

Tests

Added tests for the aptos mechanisms package

For TypeScript: Run cd typescript/packages/mechanisms/aptos && pnpm test

Checklist

I have formatted and linted my code
All new and existing tests pass
My commits are signed (required for merge) -- you may need to rebase if you initially pushed unsigned commits

cb-heimdall · 2026-01-15T02:25:04Z

🟡 Heimdall Review Status

Requirement Status More Info

Reviews

🟡 0/1

Denominator calculation

Show calculation

1 if user is bot 0

1 if user is external 0

2 if repo is sensitive 0

From .codeflow.yml 1

Additional review requirements

Show calculation

Max	0

0

From CODEOWNERS 0

Global minimum 0

Max 1

1

1 if commit is unverified 0

Sum 1

vercel · 2026-01-15T02:25:04Z

@jtang17 is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

typescript/packages/mechanisms/aptos/src/exact/client/register.ts

typescript/packages/mechanisms/aptos/src/exact/client/scheme.ts

typescript/packages/mechanisms/aptos/src/exact/facilitator/register.ts

typescript/packages/mechanisms/aptos/src/exact/server/register.ts

typescript/packages/mechanisms/aptos/src/exact/server/scheme.ts

typescript/packages/mechanisms/aptos/src/exact/facilitator/scheme.ts

phdargen · 2026-01-26T13:08:16Z

Cross-checking the verify implementation with the specs:

x402/specs/schemes/exact/scheme_exact_aptos.md

Lines 106 to 118 in 1884274

    
           Steps to verify a payment for the `exact` scheme: 
        
           1. **Extract requirements**: Use `payload.accepted` to get the payment requirements being fulfilled. 
        
           2. Verify `x402Version` is `2`. 
        
           3. Verify the network matches the agreed upon chain (CAIP-2 format: `aptos:1` or `aptos:2`). 
        
           4. Deserialize the BCS-encoded transaction and verify the signature is valid. 
        
           5. Verify the transaction sender has sufficient balance of the `asset` to cover the required amount. 
        
           6. Verify the transaction contains a fungible asset transfer operation (e.g., `0x1::primary_fungible_store::transfer` or `0x1::fungible_asset::transfer`). 
        
           7. Verify the transfer is for the correct asset (matching `requirements.asset`). 
        
           8. Verify the transfer amount matches `requirements.amount`. 
        
           9. Verify the transfer recipient matches `requirements.payTo`. 
        
           10. Simulate the transaction using the Aptos REST API to ensure it would succeed and has not already been executed/committed to the chain. 
        
           11. Verify the transaction has not expired (check sequence number and expiration timestamp). Note: A buffer time should be considered to account for network propagation delays and processing time.

2: Verify x402Version is 2 check is missing
5: Balance check is missing. I suppose simulation would fail, but checking beforehand provides clearer error messages
6: specs mentions two valid functions 0x1::primary_fungible_store::transfer or 0x1::fungible_asset::transfer, implementation only accepts the former
11: Not checked

SVM has an additional security check to prevent the facilitator from signing away their own tokens, please review if this would also be needed in your case

x402/typescript/packages/mechanisms/svm/src/exact/facilitator/scheme.ts

Lines 202 to 211 in 1884274

    
           // Verify that the facilitator's signers are not transferring their own funds 
        
           // SECURITY: Prevent facilitator from signing away their own tokens 
        
           const authorityAddress = parsedTransfer.accounts.authority.address.toString(); 
        
           if (signerAddresses.includes(authorityAddress)) { 
        
             return { 
        
               isValid: false, 
        
               invalidReason: "invalid_exact_svm_payload_transaction_fee_payer_transferring_funds", 
        
               payer, 
        
             }; 
        
           }

phdargen · 2026-01-26T13:24:01Z

It would be great if you could add some integration tests as well, see eg https://github.com/coinbase/x402/blob/main/typescript/packages/mechanisms/evm/test/integrations/exact-evm.test.ts

phdargen · 2026-01-26T13:32:56Z

Thanks a lot for the contribution @jtang17, this looks great!

I highlighted a few places above, where I think the implementation could be even more aligned with the existing evm/svm mechanisms. The verify implementation might also need some more hardening.

I would like to run some tests myself but I could't figure out how to get wAPT on testnet, could you please advice? Got at least some APT for the facilitator

jtang17 · 2026-01-27T00:28:08Z

Thanks a lot for the contribution @jtang17, this looks great!

I highlighted a few places above, where I think the implementation could be even more aligned with the existing evm/svm mechanisms. The verify implementation might also need some more hardening.

I would like to run some tests myself but I could't figure out how to get wAPT on testnet, could you please advice? Got at least some APT for the facilitator

Thanks for the feedback. I've addressed the feedback and made the mechanism more consistent - I did also end up updating the v2 scheme for Aptos as part of this.

You can get testnet APT either https://aptos.dev/network/faucet or through an account on https://geomi.dev (https://geomi.dev/manage/faucet) and testnet USDC here: https://faucet.circle.com/

phdargen · 2026-01-29T02:28:10Z

e2e/test.ts

Please add log( APTOS: ${networks.aptos.name} (${networks.aptos.caip2})); here

phdargen · 2026-01-29T02:34:23Z

Thanks a lot for the quick update @jtang17, the changes look good and I ran the integration and e2e tests successfully!

Concerning the integration tests could you please add aptos here:
https://github.com/coinbase/x402/blob/main/typescript/package.json#L24C1-L25C1

Concerning the e2e tests, could you please complete them by adding aptos to hono/next servers and axios client?
Also please add aptos env vars to e2e/clients/fetch/.env-local etc

phdargen · 2026-01-29T02:36:40Z

typescript/packages/mechanisms/aptos/README.md

+- **Sponsored Transactions**: Facilitators can pay gas fees on behalf of clients
+- **Fungible Asset Transfers**: Uses Aptos's native `primary_fungible_store::transfer`
+- **Network Support**: Mainnet (`aptos:1`) and Testnet (`aptos:2`)
+


Suggest to add link to faucets here

phdargen · 2026-01-29T02:38:52Z

typescript/packages/mechanisms/aptos/src/exact/facilitator/scheme.ts

+      const isPrimaryFungibleStore =
+        AccountAddress.ONE.equals(moduleAddress) &&
+        moduleName === "primary_fungible_store" &&
+        functionName === "transfer";
+
+      const isFungibleAsset =
+        AccountAddress.ONE.equals(moduleAddress) &&
+        moduleName === "fungible_asset" &&
+        functionName === "transfer";
+


Sorry I am not that familiar with aptos, could you elaborate a bit whats the difference between these functions and why the implementation picks one over the other?

Added a note about when primary_fungible_store::transfer would be used vs fungible_asset::transfer

typescript/packages/mechanisms/aptos/src/exact/facilitator/register.ts

phdargen · 2026-02-03T02:39:23Z

I see you made some changes @jtang17, please ping me when its ready to review again

There seem to be some merge conflicts that still need to be resolved and changes in the go package that should be reverted

jtang17 · 2026-02-03T04:35:35Z

I see you made some changes @jtang17, please ping me when its ready to review again

There seem to be some merge conflicts that still need to be resolved and changes in the go package that should be reverted

@phdargen - just rebased the dependency update and reverted go changes - PR should be ready for another review

phdargen · 2026-02-03T08:53:52Z

Hey @jtang17, the go changes are still there and the workflow tests fail

phdargen · 2026-02-03T09:00:01Z

e2e/clients/axios/index.ts

 import { registerExactEvmScheme } from "@x402/evm/exact/client";
 import { registerExactSvmScheme } from "@x402/svm/exact/client";
+import { registerExactAptosScheme } from "@x402/aptos/exact/client";
+import { Account, Ed25519PrivateKey, PrivateKey, PrivateKeyVariants } from "@x402/aptos";


Please fix import

Suggested change

import { Account, Ed25519PrivateKey, PrivateKey, PrivateKeyVariants } from "@x402/aptos";

import { Account, Ed25519PrivateKey, PrivateKey, PrivateKeyVariants } from "@aptos-labs/ts-sdk";

and add "@aptos-labs/ts-sdk" to package.json

phdargen · 2026-02-03T09:06:03Z

Please configure the test.config.json files for all servers/clients e2e tests and make all Aptos env vars optional in index.ts and test.config.json

phdargen · 2026-02-03T09:10:08Z

Please make sure all integration tests pass, currently 3/9 fail

vercel · 2026-02-04T01:08:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
x402	Ready	Preview, Comment	Feb 4, 2026 1:09am

phdargen · 2026-02-04T03:41:02Z

Hi @jtang17, could you please also add a publishing workflow for the new x402/aptos package following the evm reference here:
https://github.com/coinbase/x402/blob/main/.github/workflows/publish_npm_scoped_x402_evm.yml

phdargen · 2026-02-04T03:46:39Z

e2e/servers/next/proxy.ts

+    "/api/protected-aptos-proxy": {
+      accepts: {
+        payTo: APTOS_PAYEE_ADDRESS || "0x0",
+        scheme: "exact",
+        price: "$0.001",
+        network: APTOS_NETWORK,
+      },
+      extensions: {
+        ...declareDiscoveryExtension({
+          output: {
+            example: {
+              message: "Protected endpoint accessed successfully",
+              timestamp: "2024-01-01T00:00:00Z",
+            },
+            schema: {
+              properties: {
+                message: { type: "string" },
+                timestamp: { type: "string" },
+              },
+              required: ["message", "timestamp"],
+            },
+          },
+        }),
+      },
+    },


Needs to be conditional here or e2e tests fail at runtime with RouteConfigurationError when no aptos env vars set. Same in express and hono

Suggested change

"/api/protected-aptos-proxy": {

accepts: {

payTo: APTOS_PAYEE_ADDRESS || "0x0",

scheme: "exact",

price: "$0.001",

network: APTOS_NETWORK,

},

extensions: {

...declareDiscoveryExtension({

output: {

example: {

message: "Protected endpoint accessed successfully",

timestamp: "2024-01-01T00:00:00Z",

},

schema: {

properties: {

message: { type: "string" },

timestamp: { type: "string" },

},

required: ["message", "timestamp"],

},

},

}),

},

},

...(APTOS_PAYEE_ADDRESS ? {

"/api/protected-aptos-proxy": {

accepts: {

payTo: APTOS_PAYEE_ADDRESS,

scheme: "exact",

price: "$0.001",

network: APTOS_NETWORK,

},

extensions: {

...declareDiscoveryExtension({

output: {

example: {

message: "Protected endpoint accessed successfully",

timestamp: "2024-01-01T00:00:00Z",

},

schema: {

properties: {

message: { type: "string" },

timestamp: { type: "string" },

},

required: ["message", "timestamp"],

},

},

}),

},

},

} : {}),

Updated the hono, express, and next e2e to set these conditionally.

phdargen · 2026-02-04T03:49:17Z

e2e/servers/next/proxy.ts

+  matcher: [
+    "/api/protected-proxy",
+    "/api/protected-svm-proxy",
+    ...(APTOS_PAYEE_ADDRESS ? ["/api/protected-aptos-proxy"] : []),


This fails with

Next.js can't recognize the exported `config` field in route. `matcher` needs to be a static string or array of static strings or array of static objects. 120 | // Configure which paths the middleware should run on 121 | // Aptos path is only included if APTOS_PAYEE_ADDRESS is configured > 122 | export const config = { | ^^^^^^ 123 | matcher: [ 124 | "/api/protected-proxy", 125 | "/api/protected-svm-proxy",

I think here the route can be added unconditionally, please test

Updated - it can be.

jtang17 · 2026-02-04T06:03:02Z

@phdargen workflow has been added for the aptos package - e2e tests seem to be passing though with some bazaar discovery issues when you do not run the tests with all options enabled (I think unrelated to these changes)

jtang17 · 2026-02-11T18:44:59Z

@phdargen - are there any remaining changes needed for this PR?

erikreppel-cb · 2026-02-13T01:42:17Z

@jtang17 apologies, @phdargen is on vacation, mind resolving conflicts?

jtang17 · 2026-02-13T03:56:52Z

@erikreppel-cb @phdargen - resolved the conflicts!

phdargen · 2026-02-13T04:37:40Z

Hi @jtang17, my comments are all addressed and I successfully tested the integration + e2e tests last week.

@CarsonRoscoe will test the vercel deployment of the testnet facilitator before we get this in, thanks for your patience 🙏

github-actions bot added typescript sdk Changes to core v2 packages examples Changes to examples labels Jan 15, 2026

jtang17 force-pushed the aptos-mechanism branch from b26c731 to 916aa6f Compare January 20, 2026 23:42

github-actions bot added go and removed go labels Jan 21, 2026

erikreppel-cb requested a review from CarsonRoscoe January 25, 2026 02:31

phdargen self-assigned this Jan 25, 2026